% $Revision$
% $Date$
% $Id$


\chapter{Packages} \label{packages} \index{package}

\frege{} code is organized in packages. One source file contains
exactly one package. Compilation of a package creates an  intermediary \java{}
source file that contains the definition of a public class whose fully qualified name equals the \frege{} package name. Finally, the \java{} compiler is invoked to compile the intermediate file, which results in at least one class file.

For example:

\begin{code}
package pack.A where  -- frege code
-- declarations and bindings
\end{code}

compiles to

\begin{code}
package pack;        // java code

public class A {
    // compiled declarations and bindings
}
\end{code}


Each source file must start with a \hyperref[packagedcl]{package declaration}.
The syntax of package names is given in \autoref{declarations}.

All components of the package name
except the last one should be in lowercase. This is because the \java{}
package name is derived from these components and \java{} has the
convention that the package name should be all lowercase.

Neither file name of the \frege{} source code file nor the path where that file is stored have to reflect or match the package name. However, the intermediate \java{} source file and the final class files are subject to the customs of \java{}. That means that the files reside in a path that resembles the package name and the file name is the class name plus a suffix.

\section{Execution of \frege{} Packages} \label{execution}

\index{function!main}
The generated \java{} code for a \frege{} package contains static fields, methods and inner classes that correspond to \frege{} values, functions and types defined in that package. If the source code contained a top level binding for the name \emph{main}, then the compiler creates a wrapper method with the signature \exq{
    static void main(java.lang.String[] args) 
}
which converts the argument array to a list, evaluates the \emph{main} function from the \frege{} code and runs the resulting IO action. 

This makes it possible to run any class file that is the result of compiling a \frege{} package that contained a definition of \emph{main} with the \term{java} command. Note that, because the generated \java{} code will contain references to \frege{} runtime code, the standard libraries and possibly other imported \frege{} packages, execution of a \frege{} package requires a class path that allows the JVM to find the required classes.


\subsection*{Special handling of the main function}

The only allowed types for \emph{main} are \exq{
    main :: [String] -> IO X\\
    main :: IO X
}
where $X$ is some arbitrary type. 
To ensure this, the compiler will provide one of the following type annotations prior to type checking: \exq{
    main :: [String] -> IO ()\\
    main :: IO ()
}

The decision which annotation is supplied depends on whether \texttt{main} \emph{looks like} a function or not.
For example, the following will result in a type error: \exq{
     main = return . const ()
}
because it doesn't look like a function, when in fact it is one.  
The type checker will expect an \texttt{IO ()} value, and this will not unify with the inferred type.

To avoid such errors, one of the following is suggested:
\begin{itemize}
\item Do not write a \texttt{main} function in point-free style.
\item Give an explicit annotation for the \texttt{main} function.
\end{itemize}

A type annotation is also required whenever the value returned from the \texttt{IO} monad is not the unit type \texttt{()}.

\subsection*{Interpretation of the value returned from \texttt{main}}

Whenever the ultimate return type of the \texttt{main} function is one of \exq{
    IO Int\\
    IO Bool
}

the wrapper method will retrieve the value and will pass it to \texttt{java.lang.System.exit} when it is an \texttt{Int}. If it is \texttt{Bool} instead, the wrapper method passes 0 for \texttt{true} and 1 for \texttt{false} to the exit method. 

Here is a program that implements the Unix utility \texttt{false} in \frege{}: \exq{
    main :: IO Bool\\
    main = return false
}

If the return type is something else, no explicit return is performed.

\example{
This example assumes that the \frege{} runtime and compiler is contained in a file \term{frege.jar} that resides in the \term{lib/} subdirectory of the users home directory and that the PATH environment variable is set so that the \term{java} and \term{javac} commands can be accessed.
\begin{flushleft}
\$ cat Hello.fr\\
package test.World where\\
main (g:\_) = println ("Hello " ++ g ++ "!")\\
main args = println "Hello World!"\\
\$ java -jar \symbol{126}/lib/frege.jar Hello.fr   \# compile the package\\
running: javac -cp \symbol{126}/lib/frege.jar:. ./test/World.java\\
\$ java -cp \symbol{126}/lib/frege.jar:. test.World \# run it by passing package name\\
Hello World!\\
\$  java -cp \symbol{126}/lib/frege.jar:. test.World  again \# pass an argument\\
Hello again!\\
\$\\
\end{flushleft}
}
\hasdiff{The \emph{main} value is either itself an IO action, 
or a function that takes a list of strings and returns an IO action. 
There is no library function to access the command line arguments. 
A \emph{main} function can appear in any package. 
In fact, a program can consist of multiple packages each defining its own \emph{main} function. 
To run a specific \emph{main} one passes the package name to an appropriate JVM launcher.
When the \emph{main} function has an ultimate return type of \texttt{IO Int} or \texttt{IO Bool}, 
the returned value will determine the exit status when run through the \texttt{static void main()} method.} 

\section{Packages and Namespaces}

The package declaration creates the namespace wherein all top level declarations 
of the package live. The namespace has itself a name,
it is the last component of the package name. Namespace names must start
with an uppercase letter. They will never conflict with names of other
kinds like type names or value constructors. 
However, having a namespace and a type with the same name $N$ can lead to confusions, as explained earlier in the section that deals with \hyperref[qualified names]{qualified names}.

All items defined at the top level of the current namespace can be
accessed with unqualified names or with a name qualified by the
namespace.


\section{Importing Packages} \label{import} \index{package!import}


A package may import any other previously compiled package with an import declaration.
A compiled package contains information about all non private type aliases, type classes, instances, 
data types, functions and values defined in it in a form that allows for quick reconstruction of the packages symbol table.
Hence, during compilation of the importing package the compiler will know the names, kinds and types of the imported items and can generate appropriate code to access them.

\begin{flushleft}
\rul{importdcl} \textbf{import} \nont{packagename}  \opt{\opt{\term{as}}\nont{namespace}} \opt{\term{public}} {\nont{importlist}}\\
\rul{importlist} \opt{\term{hiding}} \sym{(} \opt{\liste{\nont{importspec}}{\sym{,}}} \sym{)} \\
\rul{importspec} \opt{\term{public}} \nont{importitem} \opt{ \nont{alias}}\\
\rul{importitem} \nont{varid} \oder{} \nont{conid}\opt{\nont{members}}   \oder{} \nont{symop} \oder{} 
 \nont{conid}\sym{.}\nont{varid} \oder{} \nont{conid}\sym{.}\nont{conid}  \oder{} \nont{conid}\sym{.}\nont{symop} \\
\rul{alias} \nont{varid} \oder {} \nont{conid}  \oder {} \nont{symop} \gcom{must match the aliased item}\\
\rul{members} \sym{(} \opt{\liste{\nont{memspec}}{,}} \sym{)}\\
\rul{memspec} \opt{\term{public}} \nont{member} \opt{\nont{alias}}\\
\rul{member} \nont{varid}  \oder {} \nont{symop} \oder {} \nont{conid} \\
\rul{namespace} \nont{conid} \\
\end{flushleft}

\hasdiff{There is no special syntax for so-called "qualified" imports. In \frege{}, all imports are basically qualified, as is explained in the following pages.}

Import declarations are processed in the order they occur in the program text. 
However, their placement relative to other declarations is immaterial. 
Even so, it is considered good style to write all import declarations somewhere near the top of the program.

An import encloses the following steps:
\begin{itemize}
\item The class file corresponding to the imported package is loaded.
The class file must exist in the current class path or in a path given
with compiler command line flags.
\item A new namespace is created for the import. If no name for the name
space was specified, the last component of the given package name is
used.
\item Items defined in the imported package are extracted from the class file
data and their definition is stored in the new name space.
\item The import list will be processed to give certain imported items names in the current namespace, so that they may be accessed with unqualified names. This process of linking is laid out in the following sections.
\end{itemize}

It is not possible to import a \java{} class file that does not result
from the compilation of a \frege{} source file.

Different packages must be imported into different name spaces.

It is possible to make use of types or classes that have no valid name in the current package. 
This is the case, for instance, when a package A declares a data type, 
package B imports this type and defines functions that use this type 
and package C imports and uses that function from B, but does not import A. 
Apart from the fact that some type signatures can't be written in C this is no problem.

\subsection{Import lists}

All non private definitions (i.e. functions, values, types, constructors,
type classes and operators) of the imported package will be accessible in
the importing package through identifiers qualified with the associated
name space name.

Instances play a special role insofar as they cannot be named and hence cannot appear in import lists. 
Therefore they will be automatically known, no matter how the import list looks like.  

Often one wishes to name some imported items without qualifiers. This
can be accomplished by listing those items in the import list:

\example{import math.Rational as R (gcd, Rat)}

This causes the function {\tt Rational.gcd} to be known under the
name {\tt gcd} in the current package. Also, if there is a constructor
or type {\tt Rat} in {\tt math.Rational}, it will be known in the
current package. Both items can still be named as {\tt R.gcd} or {\tt
R.Rat}.

A value constructor may have the same name as a type constructor, type alias or class. 
It follows that mentioning an unqualified constructor name in an import list can be ambiguous. 
This is resolved in favor of type names, i.e. if a type, alias  or class with that name exists in the imported package, 
it will be linked to the current namespace. 
To import a value constructor with an ambiguous name, it must be qualified with its type name in the import list.
\example{\\
package Imported where\\
class C where { ... }\\
data Notes = C $|$ D $|$ E $|$ F $|$ G $|$ H $|$ A $|$ B\\
\\
package Importing where\\
import Imported (C)       -- class C\\
import Imported (Notes)   -- data type Notes and its public constructors\\
import Imported (Notes.C) -- just the data constructor
}

\paragraph*{Controlling import of data constructors and members}

A class name in an import list can be followed by a list of class operations that should be available in the namespace of the importing package. If the list is empty, only the class name itself is imported, access to the class operations are possible through names that are qualified with the class name. If the list is missing, all public class operations are available. 

Likewise, a type name in an import list can be followed by a list of names declared in that type that should be linked to the namespace of the importing package in addition to the type name itself. If the list is empty, no additional names are linked. If the list is missing, all public constructor names are linked.

This feature can be used to prevent unwanted linking of constructor names to avoid name clashes, like in the following example:

\example{\\
package A where data T1 = T ....\\

package B where data T2 = T ...\\

package C where\\
import A( T1() )\\
import B( T2 )  -- hence T means T2.T
}

Like with items in the import list, data members can be  \hyperref[renameitem]{renamed} 
or  \hyperref[reexport]{re-exported}.
  
An alternative solution for the constructor name clash problem would be:

\example{\\
package A where data T1 = T ....\\

package B where data T2 = T ...\\

package C where\\
import A( T1( T  TA) )  -- TA means A.T1.T \\
import B( T2( T  TB) )  -- TB means B.T2.T
}

\paragraph*{Empty import list} If the import list is empty, no named items are linked to the current namespace. Nevertheless, as before, all items of the imported package can be accessed with qualified names.

\subsection{Importing all public items}

In addition, it is possible to link all public definitions of a
package into the namespace of the importing package by not giving an import list at all.

This will not make available the items declared \term{protected}. 
Protected items are linked only when explicitly mentioned in an import list.

\example{\\
import math.Rational}

\subsection{Renaming on import} \label{renameitem}

An item can be put in the current namespace with a different name. However, \nont{conid}s can only be aliased to \nont{conid}s while \nont{varid}s and \nont{symop}s can not be aliased to \nont{conid}s.

This is useful to avoid name clashes or to adapt naming conventions\footnote{
Be aware, though, that error messages may report the original qualified name.}.

Multiple aliases are possible for a single item.

\example{\\
import math.Rational (gcd greatestCommonDivisor, gcd ggT)}

It is important to understand that the qualified name of an imported item remains unaffected by renaming. 
All names created by imports in the current namespace are merely symbolic links to the original item. 
Hence, after the import of the example, the names \term{Rational.gcd}, \term{greatestCommonDivisor} and \term{ggT} reference the same item. 

\subsection{Re-exporting imported items} \label{reexport}

It is possible to have a package re-export all or some of its imported items 
along with the items declared in the package itself, if any\footnote{
It is perfectly legal for a package to contain nothing but import declarations.}, 
so that importing  packages can import many related items from possibly many different packages with one import.

A library designer can use this feature, especially in combination with item renaming, 
to hide implementation details of his library, 
such as package names, where and under what name exactly an item is defined etc.,
by providing a single package defining the "official" interface of the library. 
If the library is redesigned later, the package defining the interface can be adapted accordingly 
so that backwards source compatibility can be maintained\footnote{
However, binary backwards compatibility can not be achieved this way, because on the \java{} and JVM level any class,
method, etc. has only one unambiguous name.}.

To re-export a single item, one writes \term{public} before its name in the import list. Note that it is the alias name that will be exported for renamed items.
To re-export all items in the import list or just all public items when there is no import list, one writes \term{public} after the package name.

\example{\\
package x.y.API where\\
import x.y.z.Sub1 (public creat  create, public fold  reduce)\\
import x.y.z.Sub2 public hiding (deprecated1, deprecated2, ...)\\
import x.y.contributed.byXY.Utilities public\\

package XYClient where\\
import x.y.API   \\
-- makes available create, reduce, non deprecated items from Sub2\\
-- and public utilities from contributor XY, but the client need not\\
-- know all those details.
}

\subsection{Importing all but some items}

If the import list is preceded by the word "\term{hiding}", all public items but the named ones are made available for unqualified access in the current namespace.

\example{import math.Rational hiding(gcd)}

Note that for the names listed in a hiding list, the re-export and the renaming syntax do not make sense. 
Anyway, it is still possible to re-export the items effectively linked this way by placing a "\term{public}" before the "\term{hiding}".


\subsection{Name clashes}

It is permitted to overwrite a previously imported name through a declaration or binding.
All unqualified uses of that name are resolved to refer to the declaration from the current package, 
but the imported item is still available under its qualified name.
The compiler shall emit a warning in such cases.

It is also possible that an import overwrites an item in the current namespace that was introduced through a previous import.
The compiler must emit a warning in such cases.
The unqualified name will link to the last imported item.

It is advised to use the import features described above to avoid such clashes.

\subsection{Aliasing the package name}
One can specify the name of the namespace into which
items will be imported. This makes it possible to disambiguate the
namespaces for imported packages.

Consider the case that one needs two packages whose namespace names would come out equal, as in

\example{\\
import binary.Tree\\
import balanced.Tree    -- will fail, Tree is already a name space
}

Here, the second import would fail, because namespace \texttt{Tree} already
exists. The situation can be remedied like so:

\example{\\
import binary.Tree\\
import balanced.Tree  as AVL  -- all items go in namespace AVL
}

\subsection{Multiple import}
One can import any package more than once, with different import
lists or different namespaces. 

\example{\\
import frege.List public(map, take)\\
import frege.List(sortBy)\\
import frege.List() L\hspace{1cm}-- by the way: "as" is optional
}

This would be equivalent to 

\example{\\
import frege.List(public map, public  take, sortBy)\\
import frege.List() as L
}

All public items of package \texttt{frege.List} can be named with qualifier \texttt{L.} or \texttt{List.} 
and the names of the functions \texttt{List.map},  \texttt{List.sortBy} and  \texttt{List.take} don't need to be qualified. 
In addition, \texttt{List.map} and \texttt{List.take} are re-exported, so that they will be known in every package that imports this one unrestricted.

Name clashes may occur if the effective import lists have elements in common. 

\subsection{Implicit \texttt{Prelude} import}
The compiler behaves as if the top declarations in
the source code contained the import declaration
\ex{import frege.Prelude()}
before all other import declarations.
This ensures that all prelude definitions can be accessed through
namespace \texttt{Prelude} and, at the same time, that no other package my be imported as {\tt Prelude}.

In addition, unless a user provided import clause explicitly imports package \texttt{frege.Prelude}, the
compiler automatically provides a
\ex{import frege.Prelude}
before all other import declarations.
This results
in the desired behaviour, namely that all common operators, types and
so on can be used with unqualified names.


\subsection{Rules for Namespaces}

When a package is imported, all symbols defined in that package are made
available and can then be used in the importing package.
However, this does not apply to namespace names themselves. 
Namespaces exist only during compilation and are a means to organize the symbol table.

Therefore, namespaces used in the source code of the imported package
cannot be referenced in importing packages.

\subsection{Importing packages with instances}

Ambiguities arise when an imported package contains an instance for
the same type class and data constructor as another imported package.

In such cases, the compiler will use the instance that was imported last and for all conflicting instances a warning message like
\example{S.fr:3: data type A.A is already an instance of class Show (B.Show\_A  introduced on line 4)}
will be emitted.
The message informs about the position of the import that contains a conflicting instance (here line 3 in source file \term{S.fr}), the data type that was instantiated (\term{A.A}), the type class this instance was for (\term{Show}) and the internal name of the already existing instance (\term{B.Show\_A}) and where it was introduced (on line 4). Hence, in this package, the \term{instance Show A} from the package that is associated with namespace \term{B} whose import declaration can be found at line 4 is used.

=======
% $Revision$
% $Date$
% $Id$


\chapter{Modules} \label{modules} \index{module}

\frege{} code is organized in modules. One source file contains
exactly one module. Compilation of a module creates an  intermediary \java{}
source file that contains the definition of a public class whose fully qualified name equals the \frege{} module name. Finally, the \java{} compiler is invoked to compile the intermediate file, which results in at least one class file.

For example:

\begin{code}
module pack.A where  -- frege code
-- declarations and bindings
\end{code}

compiles to

\begin{code}
package pack;        // java code

public class A {
    // compiled declarations and bindings
}
\end{code}


Each source file must start with a \hyperref[moduledcl]{module declaration}.
The syntax of module names is given in \autoref{declarations}.

All components of the module name
except the last one should be in lowercase. This is because the \java{}
package name is derived from these components and \java{} has the
convention that the package name should be all lowercase.

Neither file name of the \frege{} source code file nor the path where that file is stored have to reflect or match the module name. However, the intermediate \java{} source file and the final class files are subject to the customs of \java{}. That means that the files reside in a path that resembles the package name and the file name is the class name plus a suffix.

\section{Execution of \frege{} Modules} \label{execution}

\index{function!main}
The generated \java{} code for a \frege{} module contains static fields, methods and inner classes that correspond to \frege{} values, functions and types defined in that module. If the source code contained a top level binding for the name \emph{main}, then the compiler creates a wrapper method with the signature \exq{
    static void main(java.lang.String[] args) 
}
which converts the argument array to a list, evaluates the \emph{main} function from the \frege{} code and runs the resulting IO action. 

This makes it possible to run any class file that is the result of compiling a \frege{} module that contained a definition of \emph{main} with the \term{java} command. Note that, because the generated \java{} code will contain references to \frege{} runtime code, the standard libraries and possibly other imported \frege{} modules, execution of a \frege{} module requires a class path that allows the JVM to find the required classes.


\subsection*{Special handling of the main function}

The only allowed types for \emph{main} are \exq{
    main :: [String] -> IO X\\
    main :: IO X
}
where $X$ is some arbitrary type. 
To ensure this, the compiler will provide one of the following type annotations prior to type checking: \exq{
    main :: [String] -> IO ()\\
    main :: IO ()
}

The decision which annotation is supplied depends on whether \texttt{main} \emph{looks like} a function or not.
For example, the following will result in a type error: \exq{
     main = return . const ()
}
because it doesn't look like a function, when in fact it is one.  
The type checker will expect an \texttt{IO ()} value, and this will not unify with the inferred type.

To avoid such errors, one of the following is suggested:
\begin{itemize}
\item Do not write a \texttt{main} function in point-free style.
\item Give an explicit annotation for the \texttt{main} function.
\end{itemize}

A type annotation is also required whenever the value returned from the \texttt{IO} monad is not the unit type \texttt{()}.

\subsection*{Interpretation of the value returned from \texttt{main}}

Whenever the ultimate return type of the \texttt{main} function is one of \exq{
    IO Int\\
    IO Bool
}

the wrapper method will retrieve the value and will pass it to \texttt{java.lang.System.exit} when it is an \texttt{Int}. If it is \texttt{Bool} instead, the wrapper method passes 0 for \texttt{true} and 1 for \texttt{false} to the exit method. 

Here is a program that implements the Unix utility \texttt{false} in \frege{}: \exq{
    main :: IO Bool\\
    main = return false
}

If the return type is something else, no explicit return is performed.

\example{
This example assumes that the \frege{} runtime and compiler is contained in a file \term{frege.jar} that resides in the \term{lib/} subdirectory of the users home directory and that the PATH environment variable is set so that the \term{java} and \term{javac} commands can be accessed.
\begin{flushleft}
\$ cat Hello.fr\\
module test.World where\\
main (g:\_) = println ("Hello " ++ g ++ "!")\\
main args = println "Hello World!"\\
\$ java -jar \symbol{126}/lib/frege.jar Hello.fr   \# compile the module\\
running: javac -cp \symbol{126}/lib/frege.jar:. ./test/World.java\\
\$ java -cp \symbol{126}/lib/frege.jar:. test.World \# run it by passing module name\\
Hello World!\\
\$  java -cp \symbol{126}/lib/frege.jar:. test.World  again \# pass an argument\\
Hello again!\\
\$\\
\end{flushleft}
}
\hasdiff{The \emph{main} value is either itself an IO action, 
or a function that takes a list of strings and returns an IO action. 
There is no library function to access the command line arguments. 
A \emph{main} function can appear in any module. 
In fact, a program can consist of multiple modules each defining its own \emph{main} function. 
To run a specific \emph{main} one passes the module name to an appropriate JVM launcher.
When the \emph{main} function has an ultimate return type of \texttt{IO Int} or \texttt{IO Bool}, 
the returned value will determine the exit status when run through the \texttt{static void main()} method.} 

\section{Modules and Namespaces}

The module declaration creates the namespace wherein all top level declarations 
of the module live. The namespace has itself a name,
it is the last component of the module name. Namespace names must start
with an uppercase letter. They will never conflict with names of other
kinds like type names or value constructors. 
However, having a namespace and a type with the same name $N$ can lead to confusions, as explained earlier in the section that deals with \hyperref[qualified names]{qualified names}.

All items defined at the top level of the current namespace can be
accessed with unqualified names or with a name qualified by the
namespace.


\section{Importing Modules} \label{import} \index{module!import}


A module may import any other previously compiled module with an import declaration.
A compiled module contains information about all non private type aliases, type classes, instances, 
data types, functions and values defined in it in a form that allows for quick reconstruction of the modules symbol table.
Hence, during compilation of the importing module the compiler will know the names, kinds and types of the imported items and can generate appropriate code to access them.

\begin{flushleft}
\rul{importdcl} \textbf{import} \nont{modulename}  \opt{\opt{\term{as}}\nont{namespace}} \opt{\term{public}} {\nont{importlist}}\\
\rul{importlist} \opt{\term{hiding}} \sym{(} \opt{\liste{\nont{importspec}}{\sym{,}}} \sym{)} \\
\rul{importspec} \opt{\term{public}} \nont{importitem} \opt{ \nont{alias}}\\
\rul{importitem} \nont{varid} \oder{} \nont{conid}\opt{\nont{members}}   \oder{} \nont{symop} \oder{} 
 \nont{conid}\sym{.}\nont{varid} \oder{} \nont{conid}\sym{.}\nont{conid}  \oder{} \nont{conid}\sym{.}\nont{symop} \\
\rul{alias} \nont{varid} \oder {} \nont{conid}  \oder {} \nont{symop} \gcom{must match the aliased item}\\
\rul{members} \sym{(} \opt{\liste{\nont{memspec}}{,}} \sym{)}\\
\rul{memspec} \opt{\term{public}} \nont{member} \opt{\nont{alias}}\\
\rul{member} \nont{varid}  \oder {} \nont{symop} \oder {} \nont{conid} \\
\rul{namespace} \nont{conid} \\
\end{flushleft}

\hasdiff{There is no special syntax for so-called "qualified" imports. In \frege{}, all imports are basically qualified, as is explained in the following pages.}

Import declarations are processed in the order they occur in the program text. 
However, their placement relative to other declarations is immaterial. 
Even so, it is considered good style to write all import declarations somewhere near the top of the program.

An import encloses the following steps:
\begin{itemize}
\item The class file corresponding to the imported module is loaded.
The class file must exist in the current class path or in a path given
with compiler command line flags.
\item A new namespace is created for the import. If no name for the name
space was specified, the last component of the given module name is
used.
\item Items defined in the imported module are extracted from the class file
data and their definition is stored in the new name space.
\item The import list will be processed to give certain imported items names in the current namespace, so that they may be accessed with unqualified names. This process of linking is laid out in the following sections.
\end{itemize}

It is not possible to import a \java{} class file that does not result
from the compilation of a \frege{} source file.

Different modules must be imported into different name spaces.

It is possible to make use of types or classes that have no valid name in the current module. 
This is the case, for instance, when a module A declares a data type, 
module B imports this type and defines functions that use this type 
and module C imports and uses that function from B, but does not import A. 
Apart from the fact that some type signatures can't be written in C this is no problem.

\subsection{Import lists}

All non private definitions (i.e. functions, values, types, constructors,
type classes and operators) of the imported module will be accessible in
the importing module through identifiers qualified with the associated
name space name.

Instances play a special role insofar as they cannot be named and hence cannot appear in import lists. 
Therefore they will be automatically known, no matter how the import list looks like.  

Often one wishes to name some imported items without qualifiers. This
can be accomplished by listing those items in the import list:

\example{import math.Rational as R (gcd, Rat)}

This causes the function {\tt Rational.gcd} to be known under the
name {\tt gcd} in the current module. Also, if there is a constructor
or type {\tt Rat} in {\tt math.Rational}, it will be known in the
current module. Both items can still be named as {\tt R.gcd} or {\tt
R.Rat}.

A value constructor may have the same name as a type constructor, type alias or class. 
It follows that mentioning an unqualified constructor name in an import list can be ambiguous. 
This is resolved in favor of type names, i.e. if a type, alias  or class with that name exists in the imported module, 
it will be linked to the current namespace. 
To import a value constructor with an ambiguous name, it must be qualified with its type name in the import list.
\example{\\
module Imported where\\
class C where { ... }\\
data Notes = C $|$ D $|$ E $|$ F $|$ G $|$ H $|$ A $|$ B\\
\\
module Importing where\\
import Imported (C)       -- class C\\
import Imported (Notes)   -- data type Notes and its public constructors\\
import Imported (Notes.C) -- just the data constructor
}

\paragraph*{Controlling import of data constructors and members}

A class name in an import list can be followed by a list of class operations that should be available in the namespace of the importing module. If the list is empty, only the class name itself is imported, access to the class operations are possible through names that are qualified with the class name. If the list is missing, all public class operations are available. 

Likewise, a type name in an import list can be followed by a list of names declared in that type that should be linked to the namespace of the importing module in addition to the type name itself. If the list is empty, no additional names are linked. If the list is missing, all public constructor names are linked.

This feature can be used to prevent unwanted linking of constructor names to avoid name clashes, like in the following example:

\example{\\
module A where data T1 = T ....\\

module B where data T2 = T ...\\

module C where\\
import A( T1() )\\
import B( T2 )  -- hence T means T2.T
}

Like with items in the import list, data members can be  \hyperref[renameitem]{renamed} 
or  \hyperref[reexport]{re-exported}.
  
An alternative solution for the constructor name clash problem would be:

\example{\\
module A where data T1 = T ....\\

module B where data T2 = T ...\\

module C where\\
import A( T1( T  TA) )  -- TA means A.T1.T \\
import B( T2( T  TB) )  -- TB means B.T2.T
}

\paragraph*{Empty import list} If the import list is empty, no named items are linked to the current namespace. Nevertheless, as before, all items of the imported module can be accessed with qualified names.

\subsection{Importing all public items}

In addition, it is possible to link all public definitions of a
module into the namespace of the importing module by not giving an import list at all.

This will not make available the items declared \term{protected}. 
Protected items are linked only when explicitly mentioned in an import list.

\example{\\
import math.Rational}

\subsection{Renaming on import} \label{renameitem}

An item can be put in the current namespace with a different name. However, \nont{conid}s can only be aliased to \nont{conid}s while \nont{varid}s and \nont{symop}s can not be aliased to \nont{conid}s.

This is useful to avoid name clashes or to adapt naming conventions\footnote{
Be aware, though, that error messages may report the original qualified name.}.

Multiple aliases are possible for a single item.

\example{\\
import math.Rational (gcd greatestCommonDivisor, gcd ggT)}

It is important to understand that the qualified name of an imported item remains unaffected by renaming. 
All names created by imports in the current namespace are merely symbolic links to the original item. 
Hence, after the import of the example, the names \term{Rational.gcd}, \term{greatestCommonDivisor} and \term{ggT} reference the same item. 

\subsection{Re-exporting imported items} \label{reexport}

It is possible to have a modules re-export all or some of its imported items 
along with the items declared in the module itself, if any\footnote{
It is perfectly legal for a module to contain nothing but import declarations.}, 
so that importing  modules can import many related items from possibly many different modules with one import.

A library designer can use this feature, especially in combination with item renaming, 
to hide implementation details of his library, 
such as module names, where and under what name exactly an item is defined etc.,
by providing a single module defining the "official" interface of the library. 
If the library is redesigned later, the module defining the interface can be adapted accordingly 
so that backwards source compatibility can be maintained\footnote{
However, binary backwards compatibility can not be achieved this way, because on the \java{} and JVM level any class,
method, etc. has only one unambiguous name.}.

To re-export a single item, one writes \term{public} before its name in the import list. Note that it is the alias name that will be exported for renamed items.
To re-export all items in the import list or just all public items when there is no import list, one writes \term{public} after the module name.

\example{\\
module x.y.API where\\
import x.y.z.Sub1 (public creat  create, public fold  reduce)\\
import x.y.z.Sub2 public hiding (deprecated1, deprecated2, ...)\\
import x.y.contributed.byXY.Utilities public\\

module XYClient where\\
import x.y.API   \\
-- makes available create, reduce, non deprecated items from Sub2\\
-- and public utilities from contributor XY, but the client need not\\
-- know all those details.
}

\subsection{Importing all but some items}

If the import list is preceded by the word "\term{hiding}", all public items but the named ones are made available for unqualified access in the current namespace.

\example{import math.Rational hiding(gcd)}

Note that for the names listed in a hiding list, the re-export and the renaming syntax do not make sense. 
Anyway, it is still possible to re-export the items effectively linked this way by placing a "\term{public}" before the "\term{hiding}".


\subsection{Name clashes}

It is permitted to overwrite a previously imported name through a declaration or binding.
All unqualified uses of that name are resolved to refer to the declaration from the current module, 
but the imported item is still available under its qualified name.
The compiler shall emit a warning in such cases.

It is also possible that an import overwrites an item in the current namespace that was introduced through a previous import.
The compiler must emit a warning in such cases.
The unqualified name will link to the last imported item.

It is advised to use the import features described above to avoid such clashes.

\subsection{Aliasing the module name}
One can specify the name of the namespace into which
items will be imported. This makes it possible to disambiguate the
namespaces for imported modules.

Consider the case that one needs two modules whose namespace names would come out equal, as in

\example{\\
import binary.Tree\\
import balanced.Tree    -- will fail, Tree is already a name space
}

Here, the second import would fail, because namespace \texttt{Tree} already
exists. The situation can be remedied like so:

\example{\\
import binary.Tree\\
import balanced.Tree  as AVL  -- all items go in namespace AVL
}

\subsection{Multiple import}
One can import any module more than once, with different import
lists or different namespaces. 

\example{\\
import frege.List public(map, take)\\
import frege.List(sortBy)\\
import frege.List() L\hspace{1cm}-- by the way: "as" is optional
}

This would be equivalent to 

\example{\\
import frege.List(public map, public  take, sortBy)\\
import frege.List() as L
}

All public items of module \texttt{frege.List} can be named with qualifier \texttt{L.} or \texttt{List.} 
and the names of the functions \texttt{List.map},  \texttt{List.sortBy} and  \texttt{List.take} don't need to be qualified. 
In addition, \texttt{List.map} and \texttt{List.take} are re-exported, so that they will be known in every module that imports this one unrestricted.

Name clashes may occur if the effective import lists have elements in common. 

\subsection{Implicit \texttt{Prelude} import}
The compiler behaves as if the top declarations in
the source code contained the import declaration
\ex{import frege.Prelude()}
before all other import declarations.
This ensures that all prelude definitions can be accessed through
namespace \texttt{Prelude} and, at the same time, that no other module my be imported as {\tt Prelude}.

In addition, unless a user provided import clause explicitly imports module \texttt{frege.Prelude}, the
compiler automatically provides a
\ex{import frege.Prelude}
before all other import declarations.
This results
in the desired behaviour, namely that all common operators, types and
so on can be used with unqualified names.


\subsection{Rules for Namespaces}

When a module is imported, all symbols defined in that module are made
available and can then be used in the importing module.
However, this does not apply to namespace names themselves. 
Namespaces exist only during compilation and are a means to organize the symbol table.

Therefore, namespaces used in the source code of the imported module
cannot be referenced in importing modules.

\subsection{Importing modules with instances}

Ambiguities arise when an imported module contains an instance for
the same type class and data constructor as another imported module.

In such cases, the compiler will use the instance that was imported last and for all conflicting instances a warning message like
\example{S.fr:3: data type A.A is already an instance of class Show (B.Show\_A  introduced on line 4)}
will be emitted.
The message informs about the position of the import that contains a conflicting instance (here line 3 in source file \term{S.fr}), the data type that was instantiated (\term{A.A}), the type class this instance was for (\term{Show}) and the internal name of the already existing instance (\term{B.Show\_A}) and where it was introduced (on line 4). Hence, in this module, the \term{instance Show A} from the module that is associated with namespace \term{B} whose import declaration can be found at line 4 is used.

